package com.kexio.enterprise.governance.ratelimit;

import com.kexio.enterprise.governance.ratelimit.config.RateLimitConfig;
import com.kexio.enterprise.governance.ratelimit.result.RateLimitResult;
import com.kexio.enterprise.governance.ratelimit.statistics.RateLimitStatistics;
import com.kexio.enterprise.governance.ratelimit.status.RateLimiterStatus;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 限流服务接口（重构版本）
 * 
 * 采用独立文件方式组织相关类，提高代码的可维护性和可扩展性
 * 
 * @author Kexio
 * @since 1.0.0
 */
public interface RefactoredRateLimitService {

    /**
     * 检查是否允许通过（令牌桶算法）
     * 
     * @param key 限流键
     * @return 限流结果
     */
    RateLimitResult tryAcquire(String key);

    /**
     * 检查是否允许通过（指定令牌数量）
     * 
     * @param key    限流键
     * @param tokens 令牌数量
     * @return 限流结果
     */
    RateLimitResult tryAcquire(String key, int tokens);

    /**
     * 检查是否允许通过（自定义配置）
     * 
     * @param key    限流键
     * @param config 限流配置
     * @return 限流结果
     */
    RateLimitResult tryAcquire(String key, RateLimitConfig config);

    /**
     * 阻塞获取令牌
     * 
     * @param key 限流键
     * @return 限流结果
     */
    RateLimitResult acquire(String key);

    /**
     * 阻塞获取令牌（指定令牌数量）
     * 
     * @param key    限流键
     * @param tokens 令牌数量
     * @return 限流结果
     */
    RateLimitResult acquire(String key, int tokens);

    /**
     * 阻塞获取令牌（带超时）
     * 
     * @param key        限流键
     * @param tokens     令牌数量
     * @param timeoutMs  超时时间（毫秒）
     * @return 限流结果
     */
    RateLimitResult acquire(String key, int tokens, long timeoutMs);

    /**
     * 检查剩余令牌数量
     * 
     * @param key 限流键
     * @return 剩余令牌数
     */
    long getAvailableTokens(String key);

    /**
     * 重置限流器
     * 
     * @param key 限流键
     */
    void reset(String key);

    /**
     * 批量重置限流器
     * 
     * @param keys 限流键列表
     */
    void batchReset(List<String> keys);

    /**
     * 设置限流配置
     * 
     * @param key    限流键
     * @param config 限流配置
     */
    void setConfig(String key, RateLimitConfig config);

    /**
     * 获取限流配置
     * 
     * @param key 限流键
     * @return 限流配置
     */
    RateLimitConfig getConfig(String key);

    /**
     * 删除限流器
     * 
     * @param key 限流键
     */
    void remove(String key);

    /**
     * 获取所有限流器键
     * 
     * @return 限流器键集合
     */
    java.util.Set<String> getAllKeys();

    /**
     * 获取限流统计信息
     * 
     * @param key 限流键
     * @return 统计信息
     */
    RateLimitStatistics getStatistics(String key);

    /**
     * 获取所有限流统计信息
     * 
     * @return 统计信息映射
     */
    Map<String, RateLimitStatistics> getAllStatistics();

    /**
     * 清空统计信息
     * 
     * @param key 限流键
     */
    void clearStatistics(String key);

    /**
     * 检查限流器是否存在
     * 
     * @param key 限流键
     * @return 是否存在
     */
    boolean exists(String key);

    /**
     * 预热限流器
     * 
     * @param key    限流键
     * @param tokens 预热令牌数
     */
    void warmup(String key, int tokens);

    /**
     * 获取限流器状态
     * 
     * @param key 限流键
     * @return 限流器状态
     */
    RateLimiterStatus getStatus(String key);
}
